<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD><TITLE>throw manual page - Tcl Built-In Commands</TITLE>
<link rel="stylesheet" href="../docs.css" type="text/css" media="all">
</HEAD>
<BODY><H2><a href="../contents.htm">Tcl8.6.11/Tk8.6.11 Documentation</a> <small>&gt;</small> <a href="contents.htm">Tcl Commands</a> <small>&gt;</small> throw</H2>
<H3><A HREF="../UserCmd/contents.htm">Tcl/Tk Applications</A> | <A HREF="../TclCmd/contents.htm">Tcl Commands</A> | <A HREF="../TkCmd/contents.htm">Tk Commands</A> | <A HREF="../ItclCmd/contents.htm">[incr Tcl] Package Commands</A> | <A HREF="../SqliteCmd/contents.htm">SQLite3 Package Commands</A> | <A HREF="../TdbcCmd/contents.htm">TDBC Package Commands</A> | <A HREF="../TdbcmysqlCmd/contents.htm">tdbc::mysql Package Commands</A> | <A HREF="../TdbcodbcCmd/contents.htm">tdbc::odbc Package Commands</A> | <A HREF="../TdbcpostgresCmd/contents.htm">tdbc::postgres Package Commands</A> | <A HREF="../TdbcsqliteCmd/contents.htm">tdbc::sqlite3 Package Commands</A> | <A HREF="../ThreadCmd/contents.htm">Thread Package Commands</A> | <A HREF="../TclLib/contents.htm">Tcl C API</A> | <A HREF="../TkLib/contents.htm">Tk C API</A> | <A HREF="../ItclLib/contents.htm">[incr Tcl] Package C API</A> | <A HREF="../TdbcLib/contents.htm">TDBC Package C API</A></H3>
<H3><A NAME="M2">NAME</A></H3>
throw &mdash; Generate a machine-readable error
<H3><A NAME="M3">SYNOPSIS</A></H3>
<B>throw</B><I> type message</I><BR>
<H3><A NAME="M4">DESCRIPTION</A></H3>
This command causes the current evaluation to be unwound with an error. The
error created is described by the <I>type</I> and <I>message</I> arguments:
<I>type</I> must contain a list of words describing the error in a form that is
machine-readable (and which will form the error-code part of the result
dictionary), and <I>message</I> should contain text that is intended for
display to a human being.
<P>
The stack will be unwound until the error is trapped by a suitable <B><A HREF="../TclCmd/catch.htm">catch</A></B>
or <B><A HREF="../TclCmd/try.htm">try</A></B> command. If it reaches the event loop without being trapped, it
will be reported through the <B><A HREF="../TclCmd/bgerror.htm">bgerror</A></B> mechanism. If it reaches the top
level of script evaluation in <B><A HREF="../UserCmd/tclsh.htm">tclsh</A></B>, it will be printed on the console
before, in the non-interactive case, causing an exit (the behavior in other
programs will depend on the details of how Tcl is embedded and used).
<P>
By convention, the words in the <I>type</I> argument should go from most
general to most specific.
<H3><A NAME="M5">EXAMPLES</A></H3>
The following produces an error that is identical to that produced by
<B><A HREF="../TclCmd/expr.htm">expr</A></B> when trying to divide a value by zero.
<P>
<PRE><B>throw</B> {ARITH DIVZERO {divide by zero}} {divide by zero}</PRE>
<H3><A NAME="M6">SEE ALSO</A></H3>
<B><A HREF="../TclCmd/catch.htm">catch</A></B>, <B><A HREF="../TclCmd/error.htm">error</A></B>, <B><A HREF="../TclCmd/tclvars.htm">errorCode</A></B>, <B><A HREF="../TclCmd/tclvars.htm">errorInfo</A></B>, <B><A HREF="../TclCmd/return.htm">return</A></B>, <B><A HREF="../TclCmd/try.htm">try</A></B>
<H3><A NAME="M7">KEYWORDS</A></H3>
<A href="../Keywords/E.htm#error">error</A>, <A href="../Keywords/E.htm#exception">exception</A>
<div class="copy">Copyright &copy; 2008 Donal K. Fellows
</div>
</BODY></HTML>
